.TH std::ctype::widen,do_widen 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::ctype::widen,do_widen \- std::ctype::widen,do_widen

.SH Synopsis
   Defined in header <locale>
   public:                                                                         \fB(1)\fP
   CharT widen( char c ) const;
   public:                                                                         \fB(2)\fP
   const char* widen( const char* beg, const char* end, CharT* dst ) const;
   protected:                                                                      \fB(3)\fP
   virtual CharT do_widen( char c ) const;
   protected:
   virtual const char* do_widen( const char* beg, const char* end, CharT* dst )    \fB(4)\fP
   const;

   1,2) Public member function, calls the corresponding protected virtual member
   function do_widen overload of the most derived class. Overload \fB(1)\fP calls
   do_widen(c), overload \fB(2)\fP calls do_widen(beg, end, dst).
   3) Converts the single-byte character c to the corresponding wide character
   representation using the simplest reasonable transformation. Typically, this applies
   only to the characters whose multibyte encoding is a single byte (e.g. U+0000-U+007F
   in UTF-8).
   4) For every character in the character array [beg, end), writes the corresponding
   widened character to the successive locations in the character array pointed to by
   dst.

   Widening always returns a wide character, but only the characters from the
   basic source character set
   (until C++23)
   basic character set
   (since C++23) are guaranteed to have a unique, well-defined, widening
   transformation, which is also guaranteed to be reversible (by narrow()). In
   practice, all characters whose multibyte representation is a single byte are usually
   widened to their wide character counterparts, and the rest of the possible
   single-byte values are usually mapped into the same placeholder value, typically
   CharT(-1).

   Widening, if successful, preserves all character classification categories known to
   is().

.SH Parameters

   c    - character to convert
   dflt - default value to produce if the conversion fails
   beg  - pointer to the first character in an array of characters to convert
   end  - one past the end pointer for the array of characters to convert
   dst  - pointer to the first element of the array of characters to fill

.SH Return value

   1,3) Widened character.
   2,4) end

.SH Example


// Run this code

 #include <iostream>
 #include <locale>

 void try_widen(const std::ctype<wchar_t>& f, char c)
 {
     wchar_t w = f.widen(c);
     std::cout << "The single-byte character " << +(unsigned char)c
               << " widens to " << +w << '\\n';
 }

 int main()
 {
     std::locale::global(std::locale("cs_CZ.iso88592"));
     auto& f = std::use_facet<std::ctype<wchar_t>>(std::locale());
     std::cout << std::hex << std::showbase << "In Czech ISO-8859-2 locale:\\n";
     try_widen(f, 'a');
     try_widen(f, '\\xdf'); // German letter ß (U+00df) in ISO-8859-2
     try_widen(f, '\\xec'); // Czech letter ě (U+011b) in ISO-8859-2

     std::locale::global(std::locale("cs_CZ.utf8"));
     auto& f2 = std::use_facet<std::ctype<wchar_t>>(std::locale());
     std::cout << "In Czech UTF-8 locale:\\n";
     try_widen(f2, 'a');
     try_widen(f2, '\\xdf');
     try_widen(f2, '\\xec');
 }

.SH Possible output:

 In Czech ISO-8859-2 locale:
 The single-byte character 0x61 widens to 0x61
 The single-byte character 0xdf widens to 0xdf
 The single-byte character 0xec widens to 0x11b
 In Czech UTF-8 locale:
 The single-byte character 0x61 widens to 0x61
 The single-byte character 0xdf widens to 0xffffffff
 The single-byte character 0xec widens to 0xffffffff

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR    Applied to      Behavior as published               Correct behavior
   LWG 153 C++98      widen always called overload \fB(4)\fP calls the corresponding overload

.SH See also

   narrow invokes do_narrow
          \fI(public member function)\fP
   widen  widens characters
          \fI(public member function of std::basic_ios<CharT,Traits>)\fP
   btowc  widens a single-byte narrow character to wide character, if possible
          \fI(function)\fP
